Summary

Replaces the old executor-based AsyncClient, which wrapped the sync HttpClient in a ThreadPoolExecutor, with a native async implementation built on aiohttp. The public API surface is unchanged: clickhouse_connect.get_async_client() returns an AsyncClient with the same methods. The difference is entirely under the hood, where real async I/O replaces thread-pool delegation.

Why this change

The previous AsyncClient ran every operation in a thread pool via loop.run_in_executor(). This:

• added thread overhead and context switching
• limited the actual benefits of async I/O
• complicated resource and session management

The new implementation performs HTTP I/O natively with aiohttp, giving real concurrency benefits for async workloads.

Design

Native async I/O

Requests use aiohttp.ClientSession with a configurable TCPConnector (pool limits, keepalive). HTTP response handling is fully async. aiohttp is an optional dependency installed via pip install clickhouse-connect[async].

Streaming bridge for ClickHouse Native format

Native format parsing and serialization is synchronous CPU-bound work. The client uses a bounded queue in AsyncSyncQueue as a sync/async bridge so async network reads/writes can overlap with sync parsing/serialization in an executor.

On the query path in StreamingResponseSource, the async producer reads from the aiohttp response and the sync consumer parses in an executor. On the insert path in StreamingInsertSource, the sync producer serializes in an executor and the async consumer streams to aiohttp.

Event loop safety

Non-streaming queries methods like .query(), .query_df(), etc. are fully materialized inside the executor before returning. By the time a QueryResult is returned, all data is in memory, so synchronous iteration won't block the loop.

Streaming queries like .query_rows_stream(), .query_df_stream(), etc. detect synchronous iteration from within an async context and raise ProgrammingError immediately, prompting the caller to use async for instead.

Lazy imports

aiohttp is imported lazily so import clickhouse_connect works without it installed. Attempting to use the async client without aiohttp raises a clear ImportError with install instructions. Heavy optional dependencies (numpy, pandas, pyarrow, polars) are also lazily loaded, matching the sync client.

Breaking changes

• AsyncClient(client=sync_client) no longer works. Use get_async_client() or create_async_client().
• The executor_threads and executor parameters have been removed from create_async_client().
• pool_mgr is rejected on the async path with a message pointing to connector_limit / connector_limit_per_host.
• The internal module clickhouse_connect.driver.aiohttp_client no longer exists. AsyncClient is importable from clickhouse_connect.driver as before.

Migration

# Before (no longer works):
sync_client = clickhouse_connect.get_client()
async_client = AsyncClient(client=sync_client)

# After:
async_client = await clickhouse_connect.get_async_client(host="...", port=8123)

The async client API is otherwise identical. All query, insert, and streaming methods have the same signatures.

Tests

The full integration test suite runs parametrized across both sync and async clients. Dedicated async tests in test_async_features.py cover concurrency, streaming cleanup, session protection, timeouts, and error isolation.

Performance

Benchmarks comparing the old executor-based client against the native async client showed speedups ranging from parity to 75% depending on workload, with an geometric average improvement around 16% across a wide range of realistic workloads. P95 latencies also improved significantly.

Trade-offs

• ClickHouse Native format parsing and serialization is CPU-bound and still runs in a thread pool executor. The async benefit is in I/O concurrency i.e. overlapping network reads/writes with parsing, not in making the parsing itself async.
• Non-streaming query results e.g. .query(), .query_df(), etc. are fully materialized in the executor before returning to the caller, which is the expected behavior for those APIs. Streaming variants like .query_rows_stream(), etc. are available for incremental processing.

Checklist

• Unit and integration tests covering the common scenarios were added
• A human-readable description of the changes was provided to include in CHANGELOG